Prev |
Sitecore V5 introduces a vast amount of API and concept changes. We will not try to cover them all here and focus on the most often used presentation API changes.
For additional information visit http://sdn.sitecore.net. We also offer Sitecore V5 Developer training for Sitecore V4 developers to help you get up-to-speed fast.
1. Items and Databases
1.1. Fundamental
Fundamental concepts such as templates, masters and fields remain the same. The API, however, has been completely redesigned to allow strongly-typed fine-grained access.
Contrary to Sitecore V4, master and web databases are completely identical. API, therefore, has been simplified to single Sitecore.Data.Database and Sitecore.Data.Items.Item classes. Database is used to get and search for Items and each Item is bound to the database.
To get the current database you should rely on Sitecore context, avoiding using hard coded values.
Example:
Database db = Sitecore.Context.Database;
Item home = db.Items["/sitecore/content/home"]
Sitecore V4 |
Sitecore V5 |
IMasterItem, MasterItem, IWebItem, WebItem |
Sitecore.Data.Items.Item |
MasterFactory, WebFactory |
Sitecore.Data.Database |
Supplementary reading:
1.2. Iteration and Search
Iteration has also been greatly simplified in favor of more .NET-native enumeration. For instance, take a look at the item.Children collection of Sitecore.Collections.ChildList class:
// iterate over all children
foreach(Item child in item.Children)
{
Response.Write(child.Name);
}
item.Axes of Sitecore.Data.Items.ItemAxes class allows more sophisticated access scenarios:
// iterate over all descendants of an item
foreach(Item descendant in item.Axes.GetDescendants())
{
...
}
To get children or descendants by name (key):
Item myItem = item.Axes.GetChild("myItem");
To find items matching the custom criteria, use Sitecore Query:
// to get all descendants of the current item with 'active' field set to 1
Item[] activeItems = item.Axes.SelectItems("//*[@active=\"1\"]");
Supplementary reading:
1.3. Getting and Setting Field Values
item.Fields collection of Sitecore.Collections.FieldCollection class allows strongly-typed field access.
string fieldValue = item.Fields["field name"].Value;
Sitecore V4 semantics are also available:
string fieldValue = item["field name"]
Modifying the item is a little different: you must explicitly start an item transaction. Failing to do so will result in exception.
using (new EditContext(item))
{
item.Fields["field name"] = value;
item["another field"] = value;
}
Supplementary reading:
1.4. Languages and Versions
Instead of supporting language and version aware methods , new Item class contains only the current language and version.
Use the following code to get the language and version of the item:
string language = item.Language.Name;
int version = item.Version.Number
Instead of using item.GetFieldValue(“field name”, “en”) to get the field value in specific language, you retrieve the item in that language right from the start in Sitecore V5:
Item home = database.Items[“/sitecore/content/home”, Languge.Predefined.English];
string fieldValue = home [“field name”]; // explicitly in English
If you omit the language, the context language (Sitecore.Context.Language) will be used.
The same applies to versions: the last version of an item is loaded by default. Use overloaded item getters to specify the version you need:
// get the 3rd version of ‘home’ item
Item home = database.Items[“/sitecore/content/home”, Version.Parse(3)]
2. State
Sitecore.State of Sitecore V4 was greatly extended and moved to Sitecore.Context.
The most often used properties by visualization logic are:
Sitecore V4 |
Sitecore V5 |
Sitecore.State.CurrentItem Sitecore.State.MasterItem |
Sitecore.Context.Item |
Sitecore.State.User Sitecore.State.ExtranetUser |
Sitecore.Context.User |
- |
Sitecore.Context.Database |
- |
Sitecore.Context.Domain |
Sitecore.State.Language |
Sitecore.Context.Language |
Supplementary reading:
3. Security
3.1. Access Permissions
The most noticeable change to security is that often you don’t need to think about it – all security checks are handled implicitly by Sitecore API.
When rendering a page, you don’t have to check whether a user can access the current item – the user will not be allowed to see the page in the first place.
When retrieving an item or item collection you don’t need to remember to check the security: Sitecore will only return items that the current user is allowed to see.
It is possible to temporary switch the security off to regain Sitecore V4 semantics:
using (new SecurityDisabler())
{
Item secure = database.Items[“/sitecore/content/home/secure”];
}
To explicitly check the security assignments there’s a helper method for each operation:
item.Access.CanRead()
item.Access.CanWrite()
...
Note that a list of possible assignments was changed in Sitecore V5. In particular, ‘Admin’, ‘Approve’, ‘Publish’ and ‘None’ were removed. ‘Administer’ assignment controls whether a user can modify security assignments.
Sitecore V4 |
Sitecore V5 |
Sitecore.Security, Sitecore.ExtranetSecurity |
Sitecore.Context.Security |
3.2. Domains, Users and Roles
Sitecore V5 introduces the domain concept – roles, users and security assignments are bound to a specific security domain, similar to the Windows security.
The credentials are also validated against specific domain:
// login a user
DomainAccessResult result = Sitecore.Context.Domain.Login(login, password);
if (result.Success)
{
Response.Write(“Welcome”);
}
else
{
Response.Write(“Cannot log in: “ + result.Message);
}
Instead of using generic database access to retrieve the users or roles (groups in Sitecore V4) you should use methods exposed by Domain:
RoleItem[] roles = domain.GetRoles();
RoleItem developers = domain.GetRole(“developers”);
UserItem user = domain.GetUser(“user name”);
Sitecore V4 |
Sitecore V5 |
Sitecore.User, Sitecore.ExtranetUser |
Sitecore.SecurityModel.UserItem |
- |
Sitecore.SecurityModel.RoleItem |
- |
Sitecore.SecurityModel.Domain |
Supplementary reading:
4. Settings and Configuration
Sitecore.Settings from Sitecore V4 became Sitecore.Configuration.Settings in Sitecore V5, supporting most of the old functionality. It exposes a large number of predefined web.config settings and allows to read custom ones.
Use Sitecore.Configuration.Factory class to get Sitecore configuration data.
To get specific database or domain:
Database web = Sitecore.Configuration.Factory.GetDatabase(“web”);
Domain extranet = Sitecore.Configuration.Factory.GetDomain(“extranet”);
Make sure that you don’t use factory to retrieve the current facilities – always use Sitecore.Context to get the current database, current database and so on.
Supplementary reading:
Sitecore V4 |
Sitecore V5 |
Sitecore.Settings |
Sitecore.Configuration.Settings |
|
Sitecore.Configuration.Factory |
Prev